docs: add VHS-based interactive screenshot generation by HankyStyle · Pull Request #1862 · commitizen-tools/commitizen

HankyStyle · 2026-02-09T18:03:24Z

Description

This PR adds support for generating interactive GIF screenshots for cz init and cz commit commands using VHS (Video Home System), a tool for generating terminal GIFs from code.

Why VHS?

VHS is a modern tool for generating terminal recordings as GIFs.
Benefits:

Reproducible: Tape files ensure consistent output
Version-controlled: Configuration is code
Cross-platform: Works on macOS, Linux, and Windows

Checklist

I have read the contributing guidelines

Was generative AI tooling used to co-author this PR?

Yes (antigravity + Claude Sonnect 4.5)

Code Changes

Add test cases to all the changes you introduce
Run uv run poe all locally to ensure this change passes linter check and tests
Manually test the changes:
- Verify the feature/bug fix works as expected in real-world scenarios
  - Tested python scripts/gen_cli_help_screenshots.py locally
  - Verified both init.gif and commit.gif are generated correctly
- Test edge cases and error conditions
  - Tested with missing VHS installation (proper error message)
  - Tested with missing tape files (proper warning message)
- Ensure backward compatibility is maintained
  - Existing gen_cli_help_screenshots() function unchanged
- Document any manual testing steps performed
  - See "Steps to Test This Pull Request" section below
Update the documentation for the changes

Expected Behavior

Local Generation: Running python scripts/gen_cli_help_screenshots.py should generate:
- 11 SVG files in docs/images/cli_help/ (CLI help screenshots)
- docs/images/init.gif (interactive demo of cz init)
- docs/images/commit.gif (interactive demo of cz commit)
CI/CD: When documentation workflow runs:
- VHS is installed automatically
- GIF screenshots are generated alongside SVG screenshots
- Both file types are committed to the repository

Steps to Test This Pull Request

Prerequisites

# Install VHS
brew install vhs  # macOS
# or follow: https://github.com/charmbracelet/vhs#installation

Local Testing

# 1. Checkout this branch
git checkout feat/interactive-screenshots

# 2. Run the screenshot generation script
python scripts/gen_cli_help_screenshots.py

# 3. Verify generated files
ls -lh docs/images/*.gif
open docs/images/init.gif
open docs/images/commit.gif

Additional Context

codecov · 2026-02-09T18:04:38Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.98%. Comparing base (dd972c9) to head (32058e3).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1862   +/-   ##
=======================================
  Coverage   97.98%   97.98%           
=======================================
  Files          60       60           
  Lines        2686     2686           
=======================================
  Hits         2632     2632           
  Misses         54       54

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

HankyStyle · 2026-02-09T18:05:49Z

lol. I found that I can't edit this PR title name after I created it.
Please help me change it to feat(docs): add VHS-based interactive screenshot generation or other better naming.

Lee-W · 2026-02-10T03:24:50Z

not really a feat (at least not to commitizen itself), so I changed it to docs

bearomorphism · 2026-02-10T14:50:46Z

lol. I found that I can't edit this PR title name after I created it. Please help me change it to feat(docs): add VHS-based interactive screenshot generation or other better naming.

I heard from my friend that some github preview features have so terrible UI that people cannot find where to edit the PR title.

bearomorphism

Thank you for your contribution of this great documentation improvement! The new gifs look beautiful!

Nothing is really blocking this PR but the comments related to demo.gif.

docs/images/commit.gif

.github/workflows/docspublish.yml

docs/images/commit.tape

docs/images/init.tape

scripts/gen_cli_help_screenshots.py

bearomorphism · 2026-02-10T15:22:27Z

As a follow up, this can also be used to regenerate bump.gif, which can be in a separate PR

HankyStyle · 2026-02-14T17:21:41Z

Thanks @bearomorphism

I created a separate script called gen_cli_interactive_gifs.py under the scripts/ directory, which outputs gifs into a separate directory (images/cli_interactive/ ).

Here is my reorganized directory structure.

docs/images
├── bump.gif
├── bump.yml
├── cli_help
│   └── cz_version___help.svg
├── cli_interactive
│   ├── commit.gif
│   └── init.gif
├── commit.tape
└── init.tape

And I also modified pyproject.toml to support parallel screenshot generation:

"doc:screenshots".parallel = [
    { script = "scripts.gen_cli_help_screenshots:gen_cli_help_screenshots" },
    { script = "scripts.gen_cli_interactive_gifs:gen_cli_interactive_gifs" },
]

Let me know if you have any suggestions or preferences for the placement of tape/gif files.

scripts/gen_cli_interactive_gifs.py

bearomorphism

Thanks!

HankyStyle added 4 commits February 10, 2026 01:09

docs: add VHS tape for cz init interactive demo

858386a

docs: add VHS tape for cz commit interactive demo

b7a8604

ci(gen_cli_help_screenshots): add gen_interactive_screenshots function

73dd4e1

ci(workflow): add VHS support to documentation workflow

64cce9e

HankyStyle requested review from Lee-W, noirbizarre and woile as code owners February 9, 2026 18:03

github-actions bot added pr-status: wait-for-review type: feature A new enhacement proposal labels Feb 9, 2026

Lee-W changed the title ~~Feat/interactive screenshots~~ docs: add VHS-based interactive screenshot generation Feb 10, 2026

Lee-W approved these changes Feb 10, 2026

View reviewed changes

bearomorphism self-requested a review February 10, 2026 15:02

bearomorphism reviewed Feb 10, 2026

View reviewed changes

bearomorphism added pr-status: wait-for-modification and removed pr-status: wait-for-review labels Feb 13, 2026

style: remove redundant comments

2be501a

github-actions bot added pr-status: wait-for-review type: documentation labels Feb 14, 2026

HankyStyle added 5 commits February 15, 2026 00:40

docs: reorganize interactive CLI GIFs into cli_interactive directory

db79593

ci: modify file path

263d50e

refactor: extract interactive GIF generation into separate script

ee149fa

build: configure parallel screenshot generation with VHS

92c57a4

docs: update VHS tape output paths to cli_interactive directory

32058e3

HankyStyle commented Feb 14, 2026

View reviewed changes

scripts/gen_cli_interactive_gifs.py Show resolved Hide resolved

bearomorphism approved these changes Feb 14, 2026

View reviewed changes

bearomorphism merged commit afb0ed1 into commitizen-tools:master Feb 14, 2026
20 checks passed

Uh oh!

Conversation

HankyStyle commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Why VHS?

Checklist

Was generative AI tooling used to co-author this PR?

Code Changes

Expected Behavior

Steps to Test This Pull Request

Prerequisites

Local Testing

Additional Context

Uh oh!

codecov bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

HankyStyle commented Feb 9, 2026

Uh oh!

Lee-W commented Feb 10, 2026

Uh oh!

bearomorphism commented Feb 10, 2026

Uh oh!

bearomorphism left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bearomorphism commented Feb 10, 2026

Uh oh!

HankyStyle commented Feb 14, 2026

Uh oh!

Uh oh!

bearomorphism left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

HankyStyle commented Feb 9, 2026 •

edited

Loading

codecov bot commented Feb 9, 2026 •

edited

Loading